home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / src / lib / c / etc / Opt.man < prev    next >
Text File  |  1991-01-28  |  11KB  |  286 lines
  1. '\" Copyright 1991 Regents of the University of California
  2. '\" Permission to use, copy, modify, and distribute this
  3. '\" documentation for any purpose and without fee is hereby
  4. '\" granted, provided that this notice appears in all copies.
  5. '\" The University of California makes no representations about
  6. '\" the suitability of this material for any purpose.  It is
  7. '\" provided "as is" without express or implied warranty.
  8. '\" 
  9. '\" $Header: /sprite/src/lib/c/etc/RCS/Opt.man,v 1.4 91/01/28 17:00:56 kupfer Exp $ SPRITE (Berkeley)
  10. '/" 
  11. .so \*(]ltmac.sprite
  12. .HS Opt lib
  13. .BS
  14. .SH NAME
  15. Opt_Parse, Opt_PrintUsage \- Manage command line options
  16. .SH SYNOPSIS
  17. \fB#include <option.h>\fR
  18. .sp
  19. int
  20. \fBOpt_Parse\fR(\fIargc, argv, optionArray, numOptions, flags\fR)
  21. .sp
  22. void
  23. \fBOpt_PrintUsage\fR(\fIcommandName, optionArray, numOptions\fR)
  24. .SH ARGUMENTS
  25. .AS Option *optionArray
  26. .AP int argc in
  27. Number of arguments on command line.
  28. .AP char **argv in/out
  29. Command line arguments passed to main program.
  30. .AP char *commandName in
  31. Name of the program being run, usually \fIargv\fR[0].
  32. .AP Option *optionArray in
  33. An array of option descriptions.
  34. .AP int numOptions in
  35. Number of elements in optionArray, usually obtained using the
  36. \fBOpt_Number\fR macro, e.g. \fBOpt_Number\fR(optionArray).
  37. .AP int flags in
  38. If non-zero, then it specifies one or more flags that control the
  39. parsing of arguments.  Different flags may be OR'ed together.  The
  40. only flags currently defined are OPT_ALLOW_CLUSTERING and OPT_OPTIONS_FIRST.  
  41. .BE
  42. .SH DESCRIPTION
  43. .PP
  44. \fBOpt_Parse\fR parses the command line arguments of a program according
  45. to an array of option descriptions.  Starting with \fIargv\fR[1], it parses
  46. as many options as it can and returns the rest of the options in
  47. the \fIargv\fR array, compacted to the beginning of the array (starting
  48. with \fIargv\fR[1]).  The return value indicates how many options are
  49. returned in the \fIargv\fR array (including \fIargv\fR[0]).
  50. Opt_Parse returns options that don't start with ``-'' unless they
  51. are arguments for options that it parses.  \fBOpt_Parse\fR also returns
  52. any options following an \fBOPT_REST\fR option (see below for more details).
  53. .PP
  54. Each element of the array
  55. \fIoptionArray\fR has the following structure:
  56. .DS
  57. .ta 2c
  58. \fBtypedef struct\fR Option {
  59.     \fBint\fR    \fItype\fR;
  60.     \fBchar\fR    *\fIkey\fR;
  61.     \fBchar\fR    *\fIvaluePtr\fR;
  62.     \fBchar\fR    *\fIdocMsg\fR;
  63. } Option;
  64. .DE
  65. .LP
  66. The \fIkey\fR field is a string that identifies this option.  For
  67. example, if \fIkey\fR is \fBfoo\fR, then this Option will match
  68. a \fB\-foo\fR command-line option.  If \fIkey\fR is the empty
  69. string (``'') then it matches a \fB\-\fR command-line option.
  70. If \fIkey\fR is NULL, the Option
  71. will not match any command-line options (this feature is only useful
  72. for OPT_DOC options).
  73. \fIDocMsg\fR is a documentation string to print out as part of a
  74. help message.
  75. The \fItype\fR field determines what to do when this Option is
  76. matched.  It also determines the meaning of the \fIvaluePtr\fR
  77. field.  \fIType\fR should always be specified using one of the
  78. following macros:
  79. .TP
  80. \fBOPT_TRUE\fR
  81. Treats \fIvaluePtr\fR as the address of an integer, and stores
  82. the value 1 in that integer.
  83. .TP
  84. \fBOPT_FALSE\fR
  85. Treats \fIvaluePtr\fR as the address of an integer and stores
  86. the value 0 in that integer.
  87. .TP
  88. \fBOPT_CONSTANT\fR(\fIvalue\fR)
  89. This is a generalized form of OPT_TRUE and OPT_FALSE.  Treats
  90. \fIvaluePtr\fR as the address of an integer and stores \fIvalue\fR
  91. in that integer.  \fIValue\fR must be a positive integer.
  92. .TP
  93. \fBOPT_INT\fR
  94. The next argument after the one matching \fIkey\fR must contain an
  95. integer string in the format accepted by \fBstrtol\fR (e.g. ``0''
  96. and ``0x'' prefixes may be used to specify octal or hexadecimal
  97. numbers, respectively).  \fIValuePtr\fR
  98. will be treated as the address of an integer, and the value given
  99. by the next argument will be stored there.
  100. .TP
  101. \fBOPT_TIME\fR
  102. The next argument after the one matching \fIkey\fR must contain a
  103. string that is parsable as a date and time.  Currently, only two
  104. formats are recognized:
  105. .DS
  106. \fIseconds\fR
  107. .DE
  108. .IP
  109. and
  110. .DS
  111. \fIyy\fB.\fImm\fB.\fIdd\fB.\fIhh\fB.\fImm\fB.\fIss\fR
  112. .DE
  113. .IP
  114. The first form is simply the number of seconds since the start of the
  115. epoch (1 January 1970, 0 hours GMT).  The second form specifies the
  116. year (e.g., 91 or 1991),
  117. month (1-12), day of the month, hours (0-23), minutes (0-59), and
  118. seconds (0-59).  All fields must be specified.
  119. \fIValuePtr\fR
  120. will be treated as the address of a
  121. .B time_t
  122. (defined in
  123. .BR <time.h> ), 
  124. and the given time will be stored there.
  125. All times are in terms of the current timezone and daylight savings
  126. rules.
  127. .IP
  128. Note that this flavor can clobber the static buffer used by the 
  129. .B localtime
  130. library routine.
  131. .TP
  132. \fBOPT_FLOAT\fR
  133. The next argument after the one matching \fIkey\fR must contain a
  134. floating-point number in the format accepted by \fBstrtol\fR.
  135. \fIValuePtr\fR will be treated as the address of an double-precision
  136. floating point value, and the
  137. value given by the next argument will be stored there.
  138. .TP
  139. \fBOPT_STRING\fR
  140. Treats \fIvaluePtr\fR as the address of a (char *), and stores a pointer
  141. to the next argument in the location
  142. pointed to by \fIvaluePtr\fR.
  143. .TP
  144. \fBOPT_DOC\fR
  145. This option is intended primarily as a way of printing extra documentation
  146. during help message printouts.  It isn't normally used as an actual
  147. option (and normally its \fIkey\fR field is NULL).
  148. If it is invoked as an option, then the same thing happens as for
  149. the ``-?'' option:  descriptions get printed for all options in
  150. \fIoptionArray\fR and \fBOpt_Parse\fR calls exit(0) to terminate the process.
  151. .TP
  152. \fBOPT_REST\fR
  153. This option is used by programs that allow the last several of their
  154. options to be the name and/or options for some other program.  If
  155. an \fBOPT_REST\fR option is found, then \fBOpt_Parse\fR doesn't process any
  156. of the remaining arguments;  it returns them all at the beginning of \fIargv\fR.
  157. In addition, \fBOpt_Parse\fR treats \fIvaluePtr\fR as the address of an
  158. integer value, and stores in that value the index of the first of the
  159. \fBOPT_REST\fR options in the returned \fIargv\fR.  This allows the
  160. program to distinguish the \fBOPT_REST\fR options from other
  161. unprocessed options that preceeded the \fBOPT_REST\fR.
  162. .TP
  163. \fBOPT_FUNC\fR
  164. When one of these options is encountered, \fIvaluePtr\fR is treated
  165. as the address of a function which is then called
  166. with the following calling sequence:
  167. .DS
  168. .ta 1c 2c 3c 4c 5c 6c
  169. \fBint\fI
  170. func(optString, nextArg)
  171.     \fBchar\fR    *\fIoptString\fR;
  172.     \fBchar\fR    *\fInextArg\fR;
  173. {
  174. }
  175. .DE
  176. .IP
  177. The \fIoptString\fR parameter points to the current option, and
  178. \fInextArg\fR points to the next option from \fIargv\fR (or NULL
  179. if there aren't any more options in \fIargv\fR.  If \fIfunc\fR
  180. uses \fInextArg\fR as an argument to the current option (so that
  181. Opt_Parse should skip it), then it should return 1.  Otherwise it
  182. should return 0.
  183. .TP
  184. \fBOPT_GENFUNC\fR
  185. Treat \fIvaluePtr\fR as the address of a function and pass all of the
  186. remaining arguments to it in the following way:
  187. .DS
  188. .ta 1c 2c 3c 4c 5c 6c
  189. \fBint\fI
  190. genfunc(optString, argc, argv)
  191.     \fBchar\fR    *\fIoptString\fR;
  192.     \fBint\fR    \fIargc\fR;
  193.     \fBchar\fR    **\fIargv\fR;
  194. {
  195. }
  196. .DE
  197. .IP
  198. \fIArgc\fR and \fIargv\fR refer to all of the options after the
  199. one that triggered the call, and \fIoptString\fR points to the
  200. triggering option.  \fIGenfunc\fR should behave in a fashion similar
  201. to \fBOpt_Parse\fR:  parse as many of the remaining arguments as it can,
  202. then return any that are left by compacting them to the beginning of
  203. \fIargv\fR (starting at \fIargv\fR[0]).  \fIGenfunc\fR
  204. should return a count of how many arguments are left in \fIargv;
  205. \fBOpt_Parse\fR will process them.
  206.  
  207. .SH "FLAGS"
  208. .IP \fBOPT_ALLOW_CLUSTERING\fR
  209. This will
  210. permit several options to be clustered together with a
  211. single ``-'', e.g., ``foo -abc'' will be handled the same way as
  212. ``foo -a -b -c''.  OPT_ALLOW_CLUSTERING is likely to cause confusing
  213. behavior unless each option is identified with a single character.
  214. .IP \fBOPT_OPTIONS_FIRST\fR
  215. This causes \fBOpt_Parse\fR to stop parsing the command line anytime something
  216. that is not an option is detected.  Thus, a program that takes some options 
  217. followed by a command to execute (along with that command's options) can 
  218. parse its own options using OPT_OPTIONS_FIRST.  When the command to execute is 
  219. encountered, assuming it does not begin with a hyphen, \fBOpt_Parse\fR will 
  220. return the command and its arguments starting at \fIargv\fR[1], ignoring
  221. any arguments with hyphens following the first non-option.
  222. .SH "USAGE MESSAGE"
  223. .PP
  224. \fBOpt_PrintUsage\fR may be invoked to print out all the documentation strings
  225. (plus option names and default values) for a command's options.  If
  226. \fBOpt_Parse\fR encounters an option ``-?'' or ``-help'', then it will call
  227. \fBOpt_PrintUsage\fR
  228. and exit.  Note:  in some shells the question-mark must be escaped
  229. (e.g., ``foo -\e?'' in \fIcsh\fR).
  230.  
  231. .SH EXAMPLE
  232. .PP
  233. Here is an example definition of a set of option descriptions and
  234. some sample command lines that use the options.  Note the effect
  235. on argc and argv;  command arguments that get interpreted as
  236. options or option values are eliminated from argv, and argc
  237. is updated to reflect reduced number of arguments.
  238. .DS
  239. /*
  240.  * Define and set default values for globals.
  241.  */
  242. Boolean debugFlag = FALSE;
  243. int numReps = 100;
  244. char defaultFileName[] = "out";
  245. char *fileName = defaultFileName;
  246. Boolean exec = FALSE;
  247.  
  248. /*
  249.  * Define option descriptions.
  250.  */
  251. Option optionArray[] = {
  252.     OPT_TRUE, "X", (char *) &debugFlag, "Turn on debugging printfs",
  253.     OPT_INT, "N", (char *) &numReps, "Number of repetitions",
  254.     OPT_STRING, "of", (char *) &fileName, "Output filename",
  255.     OPT_REST, "x", (char *) &exec,
  256.         "File to exec, followed by any arguments (must be last argument).",
  257. };
  258.  
  259. main(argc, argv)
  260.     int argc;
  261.     char *argv[];
  262. {
  263.     Opt_Parse(argc, argv, optionArray, Opt_Number(optionArray),
  264.             OPT_ALLOW_CLUSTERING);
  265.  
  266.     /*
  267.      * the rest of the program.
  268.      */
  269. }
  270. .DE
  271. .PP
  272. Note that default values can be assigned to option variables.
  273. Also, numOptions gets calculated by the compiler in this example.
  274. Here are some example command lines and their effects.
  275. .DS
  276. prog -N 200 infile        # just sets the numReps variable to 200
  277. prog -of out200 infile     # sets fileName to reference "out200"
  278. prog -XN 10 infile        # sets the debug flag, also sets numReps
  279. .DE
  280. In all of the above examples, the return value from Opt_Parse will be 2,
  281. \fIargv\fR[0] will be ``prog'', \fIargv\fR[1] will be ``infile'',
  282. and \fIargv\fR[2] will be NULL.
  283.  
  284. .SH KEYWORDS
  285. arguments, command line, options
  286.